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Section 1. Introduction 
Road map 

This tutorial examines the fundamental skills required to build a Palm OS 
data-collection application. It leverages the development environment established in 
the previous tutorial, Building Palm OS applications, and reaches further into the Palm 
OS SDK's capabilities. In particular, this tutorial shows how to develop communications 
and database programming skills using two sample applications. The first sample 
application exercises serial-communications functionality as it exchanges data with the 
host development computer. The second sample application demonstrates the data 
manager functions including the key concept of record packing. 

This tutorial is organized into the following sections: 

* Palm OS communications capabilities 

* Sample communications program 

* Basic database capabilities 

* Sample database program 

Download the full source code from the on page section. Code snippets in this 
tutorial include: 

* Opening serial communications port 

* Sending and receiving data 

* Creating and opening a Palm OS database 

* Writing and reading records 

A subsequent tutorial in this series combines these skills to create a complete 
data-collection application capable of recording information received from an 
embedded appliance via an infrared link. 


Variety of options 

The first programming example in this tutorial focuses on serial communications. 
However, a data-collection application can involve other forms of communications. The 
Palm OS platform provides many popular communications technologies options. The 
typical Palm OS device supports a serial connection, an infrared link, and a network 
link via a modem or a network adapter. Some devices support USB and Bluetooth as 
well. Expansion boards such as Handspring's Springboard technology also broaden 
the communications options. 

The database programming examples in this tutorial apply to data-collection 
applications regardless of the communications mechanisms involved. Some 
applications do not use communications at all; they simply demand user input of data 
via manual methods such as button taps and Graffiti, or keying. 
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Conventions used in this tutorial 

There are several conventions used in this tutorial to reinforce the material presented: 

* Text to be typed in is displayed in a bold monospace font. In some code 
examples, bold is used to draw attention to a tag or element being referenced in 
the accompanying text. 

* Emphasis is used to draw attention to windows, dialog boxes, and feature names. 

* A monospace font presents file and path names. 

* Throughout this tutorial, code segments irrelevant to the discussion have been 
omitted and replaced with ellipses (...) 


About the author 

After his college basketball career came to an end without a multiyear contract to play 
for the L.A. Lakers, Frank Ableson shifted his focus to computer software design. Fie 
enjoys solving complex problems, particularly in the areas of communications and 
hardware interfacing. When not working, he can be found spending time with his wife 
Nikki and their children. Frank can be reached at frank@cfgsolutions.com. 
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Section 2. Palm OS communications capabilities 
Serial communications 

The most common form of communications on the Palm OS platform is asynchronous 
serial communications, which is commonly referred to as RS-232 . The asynchronous 
serial communications technology is versatile and prolific; it is found on an 
overwhelming majority of host systems, peripherals, and embedded devices. 

The Palm OS hardware contains a circuit known as a Universal Asynchronous 
Receiver Transmitter, or UART. The UART chip is responsible for translating 
information from bytes into pulses (or bits) moving along a wire. A UART transmits data 
by sending voltage pulses along a wire at a specified frequency known as the baud 
rate. Pulses represent a sequence of Is and Os. The receiving device, which typically 
contains another UART, collects the "high" and "low" pulses and combines them into 
bytes. 

A minimal UART connection requires three physical wires: transmit, receive, and signal 
ground. Additional control signals provide handshaking and flow of control for a serial 
connection. A UART may optionally send and receive data independently and 
concurrently, hence the "asynchronous" in the name. 

Some Palm OS devices have omitted RS-232 in favor of a Universal Serial Bus (USB) 
interface. The primary advantage of USB over RS-232 is higher data transfer speed, 
although RS-232 is more widely deployed in the field and thus enjoys a higher degree 
of compatibility. 


Infrared communications 

While laptop computers have been shipping with infrared ports for years, the Palm OS 
has brought infrared technology to the forefront of data communications. Palm OS has 
virtually coined the term beam. Users beam programs, contacts, and other pieces of 
information from one device to another. 

Physically, the Palm OS device achieves infrared communication by combining the 
on-board UART with an infrared encoding and decoding transceiver. The encoding 
transceiver converts the UART's output signals into infrared light pulses rather than 
voltage pulses out of the serial port. In a similar fashion, the device decode received 
light pulses into voltage levels and inputs them to the UART's receive pin. Flow control 
is achieved via a software protocol; there are no control signals. Due to the shared 
transmission medium of infrared light, communication is limited to one direction at a 
time. 

Wired serial communications and infrared communications are mutually exclusive on 
the Palm OS device; only one can occur at any point in time as they share the same 
UART resource. 
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Infrared communications modes: Raw IR 

Four modes of infrared communications are available. The first mode is: 

Raw Ir- The infrared transceiver is enabled and all data sent to the UART converts to 
infrared pulses rather than being sent as a signal over the wire. The infrared pulses 
conform to the IrPHY level of the IrDA.org's protocol specifications. For more 
information on the IrDA, please refer to the Resources on page 21 section. 


Infrared communications mode: IrLibrary 

The second mode is: 

IrLibrary - The IrLibrary is a Palm OS built-in shared library providing low-level 
functions for infrared programming. The IrLibrary contributes fundamental components 
of the protocol stack defined by the lrDA.org, including the Ir Link Access Protocol 
(IrLAP) and Ir Link Management Protocol (IrLMP) layers of the stack. Higher-level 
services are built on these protocols. 


Infrared communications mode: Exchange Manager 

The third mode is: 

Exchange Manager - When information is beamed from one device to another, the 
underlying protocol is known as OBEX, or Object Exchange. Palm OS programmers 
access OBEX through the Exchange Manager APIs in the Palm OS SDK. OBEX is part 
of the IrDA-defined protocol stack. Note that OBEX is defined for other transport 
mechanisms as well, such as Bluetooth. 


IrCOMM communications mode 

The fourth and final mode is: 

IrCOMM - An IrCOMM protocol enables devices to communicate wirelessly, without 
changing software operation. IrCOMM performs in the same manner as an RS-232 link 
by emulating various control signals in software. The IrDA defines IrCOMM as a 
higher-level protocol. 


Network communications 

A variety of modems, both wired and wireless, are available for Palm OS devices. 
Through the use of Serial Line Internet Protocol (SLIP) or Point-to-Point Protocol 
(PPP), the Palm OS has access to an Internet Protocol (IP) environment. Palm OS 
provides a shared library known as Net. lib for performing socket level 
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communications. Some Palm OS revisions also provide a library tor performing HTTP 
operations. 

While this tutorial does not demonstrate network-communications programming, keep 
these considerations in mind. A data-collection application may employ network 
communications as an option for moving data to and from the Palm OS device as an 
alternative to serial or infrared. However, a modem connection consumes the device's 
single UART resource. This implies that it is not possible to collect data via the infrared 
or serial port and immediately transmit the data to a remote networked host system. To 
address this limitation, use specialized hardware in an add-on device with its own 
UART, such as a Springboard module for a Handspring device. 


New serial manager 

The Palm OS SDK contains a software component known as the New Serial Manager. 
The New Serial Manager is a flexible communications API designed to support a 
variety of underlying hardware communications devices. This API replaces an earlier 
set of limited serial communications functions. The older API, known simply as Serial 
Manager, is limited to a single serial port. The New Serial Manager has support for 
multiple, concurrent port usage, although the majority of current devices still have only 
a single UART. Additionally, the New Serial Manager allows the use of virtual serial 
drivers. Virtual serial drivers allow special communications devices to appear to the 
programmer as a simple communications port. This driver mechanism allows for the 
seamless use of technologies such as infrared and Bluetooth. The New Serial Manager 
comes equipped with a special communications port known as ircm. This port enables 
the IrCOMM protocol described in the Infrared communications modes panel. 

The New Serial Manager benefits programmers with its variety of communications 
devices, which makes development easier. For example, a single program written with 
the New Serial Manager APIs is capable of communicating with a traditional RS-232 
device, an infrared device via IrCOMM, and even a Bluetooth device via the RfCOMM 
protocol. The only significant change is the port value when the device is opened. 

For more information on the New Serial Manager, please see the Resources on page 21 
section. 


Technique of choice 

This tutorial exercises the New Serial Manager. The upcoming sample program 
enables a Palm OS device to communicate with a host computer via an RS-232 link. 
The Palm OS device is connected to the host computer by the HotSync cradle. Once 
the RS-232 link is tested, the sample application is upgraded to employ IrCOMM. The 
simplicity of the upgrade demonstrates the flexibility of the New Serial Manger's 
architecture. 
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Section 3. Sample communications program 
CommsTest program 

This section walks through the basics of serial communications for the Palm OS by 
examining a complete test application. The program, named CommsTest , has four 
operations accessible via simple buttons: Open Port, Send, Show Received Data, and 
Close Port. The Open button attempts to open the standard serial port and displays an 
error message if the port is unavailable. The Send button attempts to send a simple 
text message out the port. The Show button displays any received data. The Close 
button releases the communications port by closing it. Each of these operations is 
discussed in greater depth including example code. Please see the Resources on page 21 
section for more information on downloading the full source code for this program. 


CommsTest program definitions 

Here are two definitions for the global variables and functions used in the code 
samples below: 


UIntl6 port = Oxffff; 


This port is used to hold the communications port identifier. The call to SrmOpen 
establishes this value and all subsequent New Serial Manager function invocations 
require it as well. 

UInt8 buffer[1 * 1024]; 

UIntl6 pin,pout; 


This buffer holds received data. With the help of the variables pin and pout, buffer is 
a circular buffer meaning that the oldest data in the buffer is overwritten with the most 
recently received data. Some applications require larger buffers. This example is an 
elementary circular buffer useful for demonstration purposes only: 

UInt8 InitializePort(); 
void TerminatePort(); 

void ProcessPort(UInt32 bytesavailable); 

void ShowBuffer(); 

void SendData(Char * dataP); 


These functions represent the primary operations of CommsTest and are invoked by 
the user interface handlers and the application's EventLoop. 


Opening serial communications port 

An application opens a communications resource by calling the New Serial Manager 
function SrmOpen. When successfully invoked, SrmOpen returns a port identifier, or 
portid. Use this portid in all subsequent operations on the port. The portid distinguishes 
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it from other communications resources in use. The portid value is valid until the 
SrmCiose function is invoked to discontinue use of the communications port. 

Tapping the sample application's Open Port button initiates the process of opening the 
RS-232 serial port: 


static Boolean frmMain_Open_OnSelect(EventPtr event) 
{ 

// Insert code for Open 
InitializePort(); 
return true; 

} 


InitializePort 
UInt8 InitializePort() 

{ 

Err err; 

Char buf[100]; 

MemSet(buffer,sizeof(buffer),0x00); 
pin = pout = 0; 

err = SrmOpen(0x8000,9600, &port) ; 
if (err) 

{ 

StrPrintF(buf,"Unable to open port, error is [%d]",err); 
FrmCustomAlert(Info,buf,NULL,NULL); 
return 1; 

} 

return 0; 


SrmOpen details 

The first argument to SrmOpen indicates the desired communications resource. The 
value can be either a logical port number, or the name of a particular port. Common 
values are: 

* 0x8000 -- logical value for the RS-232 serial port 

* 0x8001 - logical value for the Ir Port 

* ircm - IrCOMM virtual port name 

The second argument to SrmOpen indicates the initial baud rate desired. In the 
example program, this value is set to 9600. It is quite common to change the speed 
and other port settings after a successful SrmOpen call. The New Serial Manager 
function, SrmControl, is used for controlling port characteristics such as baud rate 
and flow-control settings. The functions SrmGetstatus and SrmGetDeviceinfo 
allow querying of current port settings. The sample application does not attempt to 
change any parameters; the default settings are sufficient. 

The third and final argument to the SrmOpen function is the address of a variable of 
type uintl6. Upon a successful open, this variable is populated with a value 
identifying the open communications resource, or described earlier, the port identifier. 
All subsequent invocations of New Serial Manager functions require this value as the 
first parameter. 
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The return value from the SrmOpen function is the standard Palm OS Err data type. A 
return value of zero indicates success. Any other value represents an error condition. 
The Palm OS SDK documentation enumerates the possible error conditions for the 
SrmOpen function. 


Sending and receiving data 

Once the communications resource is open and the communications characteristics 
are set to their desired state, the transfer of information can commence. The 
CommsTest application sends a simple text message when instructed to do so. The 
Send button initiates this process. Here is the code: 

First, the user interface handler: 


static Boolean frmMain_Send_OnSelect(EventPtr event) 
{ 

// Insert code for Send 

SendData ("Some data for you ."); 

return true; 

} 


This function performs the actual transmission via the New Serial Manager function, 

SrmSend: 

void SendData(Char * dataP) 

{ 

Err err; 

UInt32 bytestosend = StrLen(dataP); 

UInt32 bytessent = 0; 

Char buf[100]; 

bytessent = SrmSend(port,(const void *)dataP,bytestosend,Serr); 
if (bytessent != bytestosend || err != 0) 

{ 

StrPrintF(buf,"Error during send [%ld] out of [%ld] err = [%d]",bytessent,bytest 
FrmCustomAlert(Info,buf,NULL,NULL); 

} 


The function attempts to send the entire string represented by the single argument to 
the function, dataP. If an error occurs during the attempt, an Alert notifies the user. 
Notice that this function expects a null-terminated string; however, the SrmSend 
function can accept binary data as well. 

The SrmSend function requires a valid port identifier as the first argument. The 
additional arguments to the function are the base address of a memory buffer 
containing the data to be sent, the number of bytes to send, and the address of a 
variable to record any errors which might occur during the send attempt. The return 
code of the function indicates the number of bytes actually sent to the port. 


The send buffer 
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There are four functions available in the New Serial Manager concerning the sending of 
data. The most commonly used function, SrmSend is demonstrated in the CommsTest 
application. By invoking the SrmSend function, the data passes through a FIFO (first in, 
first out) buffer. The other functions each have a special purpose in manipulating this 
FIFO buffer. 

The SrmSendCheck function obtains the number of bytes remaining to be sent in the 
FIFO transmit buffer. The first argument is, as usual, the portid. The second argument 
is the address of a uint32 variable. This second value is populated with the current 
depth of the FIFO transmit buffer. A zero return value indicates success, with a 
non-zero value indicating an error. 

The SrmSendFlush function flushes the transmit FIFO buffer without sending the 
contents. Use this function when initializing a communications resource. Open the port 
and then flush the transmit buffer to ensure that no stray data finds its way to a target 
device. 

The SrmSendWait function attempts to send any data remaining in the transmit buffer. 
It returns when either the buffer has been completely sent, or the elapsed time exceeds 
the port timeout value known as ctsTimeout. The ctsTimeout is set by the 
SrmControl function. 

The Palm OS SDK documentation provides useful information on the usage of the 
SrmControl function. 


Looking for data 

The previous tutorial in this series discussed the role of the EventLoop function in 
Palm OS applications. The CommsTest application inserts a small amount of code into 
its EventLoop in order to poll for data received at the port. When data is available, 
another function is invoked to read it from the receive buffer. Note in the code below 
the second argument to the EvtGetEvent function - the value is an integer value of 
100, not the usual constant evtWaitForever. This value of 100 causes the function 
to timeout in 100 system ticks, or 1 second if another event has not occurred. This is a 
low polling frequency for a communications application. Plowever, it is sufficient for a 
simple demonstration. Also note the use of the TerminatePort function at the end of 
the EventLoop. This performs a last effort to close the port upon application exit, just 
in case the Close Port button is never tapped. 


Modifying the EventLoop function 

Plere is the EventLoop function modified to poll for received data: 


static void EventLoop(void) 

{ 

Err error; 

EventType event; 

UInt32 bytesavailable; 
// Main event loop 
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} 


do 

{ 


} 

while 


// Get next event 

EvtGetEvent(Sevent, SysTicksPerSecond() ) ; 
if (port != Oxffff) 

{ 

SrmReceiveCheck(port,&bytesavailable); 
if (bytesavailable > 0) 

{ 

ProcessPort(bytesavailable); 

} 


} 

// 

if 

{ 


} 


Handle event 

(!SysHandleEvent(Sevent)) 


if 

{ 

} 


(IMenuHandleEvent(0, Sevent, Serror)) 

if (!ApplicationHandleEvent(Sevent)) 
FrmDispatchEvent(Sevent) ; 


(event.eType != appStopEvent); 
TerminatePort() ; 


When the communications port is open, the variable port equates to something other 
than Oxffff. Each pass through the EventLoop, the function SrmReceiveCheck is 
invoked. This function examines the depth of the receive FIFO. If there is data 
available, control is passed to the ProcessPort function, where the received data is 
processed. 


Reading data from the port 

When the CommsTest application finds data available at the port, it is moved into an 
application-defined circular buffer. The ProcessPort function listed below reads data 
from a New Serial Manager-managed FIFO buffer and copies it into the application's 
circular buffer. 


void ProcessPort(UInt32 bytesavailable) 

{ 

UInt32 bytestoread = 0; 

UInt32 bytesread = 0; 

Err err; 

Char buf[100]; 

// read data into buffer 

bytestoread = min(sizeof(buffer)-pin,bytesavailable); 
bytesread = 

SrmReceive(port,&buffer[pin],bytestoread, SysTicksPerSecond() , Serr) ; 
if (bytesread != bytestoread || err != 0) 

{ 

StrPrintF(buf,"Error during read [%d] out of [%d] err = [%d]",bytesread,bytestor« 
FrmCustomAlert(Info,buf,NULL,NULL); 

} 

pin += bytesread; 

if (pin >= sizeof(buffer)) pin = 0; 
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CommsTest makes use of the SrmReceive function to read data from the receive 
FIFO. The arguments to the SrmReceive function include the usual port identifier, the 
starting address of a buffer to store the read data, the number of bytes to read, a 
timeout value, and a variable to record any errors during the read activity. The function 
returns the number of bytes actually read. 

SrmReceive's signature is similar to the SrmSend function, however it includes an 
additional parameter, namely the timeout. SrmReceive returns a call after reading the 
requested number of bytes or after the timeout period has expired. The timeout is 
expressed in Palm OS system ticks. The SDK function SysTicksPerSecond is used 
for determining the timing values on a specific device. Using this function to calculate a 
timeout value rather than a fixed constant allows an application to run on any Palm OS 
device, even if the underlying time granularity changes. 


The receive functions 

Similar to the Send functions, the New Serial Manager also provides functions for 
manipulating the receive FIFO buffer. 

The SrmReceiveCheck function, as described above, checks for the number of 
available bytes in the received FIFO buffer. 

SrmReceiveFlush is a useful function typically used immediately after opening a 
communications resource. This function removes all data from the receive buffer, 
minimizing the chances that an application reads stale, unwanted data from the buffer. 
In addition to the port identifier, this function takes an argument specifying a timeout 
period. When invoked, the receive buffer is flushed. The function then waits the 
requested number of system ticks, looking for more data to arrive. If additional data 
arrives, the newly arrived data is removed from the receive buffer and the function 
again waits for the full timeout period. The function will only return when an entire 
timeout period has elapsed without the receipt of additional data. 

The SrmReceiveWait function takes three arguments. After the required port 
identifier, the byte count and timeout value arguments are used to direct this function. 
The function does not return until either the receive FIFO depth reaches the requested 
byte count or the timeout period expires. 


Displaying received data 

In a real data-collection application, received data would find its way into a database. 

As database programming topics have not yet been discussed in this tutorial series, the 
CommsTest application simply displays the received data via an Alert. It is not fancy, 
but it demonstrates the successful receipt of data in the application. 

void ShowBuffer() 

{ 

FrmCustomAlert(Info,&buffer[pout],NULL,NULL); 
pout = pout + StrLen(&buffer[pout]); 
if (pout > sizeof(buffer)) pout = 0; 
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} 


Testing environment 

An important aspect to communications application development is the test 
environment. Having a simple, "control" environment to verify communications 
functionality is crucial to the success of the project as well as to the sanity of the 
developer! 

Be sure to install the CommsTest application onto the Palm OS device. Leave the 
device in the cradle. 

Test CommsTest with a terminal-emulation package such as HyperTerminal. 

1. Identify the COM port used by the HotSync Manager; make a note of this value. 

2. Exit the HotSync manager software. 

3. Configure HyperTerminal to communicate directly with the same COM port used 
by the HotSync Manager. 

4. Set the baud rate to 9600, the data bits to 8, the stop bits to 1, and the parity to 
None. 

5. Initiate the connection; HyperTerminal refers to this as the "Call". 

Establishing a connection varies in other communications packages. 

On the Palm device, start the CommsTest application. Select the Open Port button. 
Tap on the Send button. Data should appear on the HyperTerminal window. Next, key 
a message into the HyperTerminal window. This data is stored in the circular buffer in 
CommsTest via the ProcessPort function described above. Tap on the Show 
Received Data button on the Palm OS form. An Alert displays the keyed message on 
the Palm device. Tap on the Close Port button to end the test. 

The Palm OS Emulator provides an alternative testing environment. POSE can use the 
communications ports available on the host computer. Therefore, it provides a real 
serial connection to CommsTest running on POSE. With POSE's serial port redirected 
to the computer's port, the emulator-hosted CommsTest application can communicate 
with any other device connected to the host computer. This can even be a Palm device 
running CommsTest. 


Using POSE 

Follow these steps to get started with POSE: 

1. Close HotSync manager if it is running. 

2. Start POSE and install the CommsTest application. 

3. Right mouse click on the face of POSE and select Settings | Properties. 

4. Under the Communications heading, select the appropriate COM port for Serial 
Emulation. 

5. Close the dialog. 
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6. Start CommsTest on the emulator. 

7. Start CommsTest on the device while it is sitting in the HotSync cradle. 

The programs can now send messages back and forth. 

Using POSE has a few advantages over testing on the real device: 

* Loading a new program revision on POSE is done quickly, without the need for a 
full HotSync. 

* POSE can log serial events and data. (See Settings | Logging on the POSE 
menu). 

* Applications running on POSE, and even communications applications, are easily 
debugged. Interactively debugging a communications application on a real device 
is impossible due to the single UART constraint. 

* Keying data into POSE is easier then using Grafitti. 

For all of the virtues of testing with POSE, remember, the application must run on a 

real device. Always test the application on the real target device before shipping. 


Switch to IrDA 

Using the New Serial Manager allows communications changes without significant 
effort. Enabling IrCOMM communications for CommsTest is done in one line of the 
program. Change the SrmOpen call from: 


err = SrmOpen(0x8000,9600,Sport) ; 


To: 


err = SrmOpen('ircm',9600,Sport); 


Now recompile. 

CommsTest is now ready for IrCOMM communications instead of RS-232. The next 
step is establishing a test environment. Here are the most readily accessible options: 

* Windows 9X laptop with infrared capability 

* Another Palm OS device running CommsTest 

* A commercially available dongle device for the serial port. These devices 
implement the IrCOMM protocol yet look like RS-232 serial to the host computer. 

The appliance used in the final tutorial in this series employs a chipset from Microchip, 
Inc. The chipset is designed as a low-cost part enabling embedded systems designers 
to add infrared communications capabilities without the complexity of implementing the 
entire IrDA stack. More information is available in the Resources on page 21 section. 

Ideally, a data-collection application should provide a user interface element for 
switching between various communications ports. This is left as an exercise for the 
reader, or alternatively there are commercially available applications providing this 
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multiple-target functionality. 
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Section 4. Database programming 
Database primer 

All data stored on a Palm OS device is organized into one or more databases. The 
Palm OS SDK functions for manipulating databases are known as the DataManager 
functions. DataManager functions are used throughout the balance of this tutorial to 
demonstrate key database usage techniques. Before jumping directly into the 
DataManager functions, there are a few important terms and data types to review: 

* Card - The Palm OS organizes memory space into database cards. Only devices 
with expansion modules have anything beyond a single card. Card numbering 
starts at position zero. All examples in this tutorial assume a single database card 
of zero. 

* LocallD - The LocallD identifies a database on a particular card. The LocallD is 
required for opening a database. 

* DmOpenRef - This represents a "database identifier" or "handle to the database." 
Most DataManager functions require a DmOpenRef as the first argument. 


Creating and opening a Palm OS database 

In order to open a database, the database must first be found or otherwise identified. 
The standard procedure for opening a database is to perform a find operation. If the 
find operation fails, the application may optionally create the database, and then 
attempt to open it. The sample code below demonstrates this technique: 


static Boolean frmMain_OPENDB_OnSelect(EventPtr event) 

{ 

Err err; 

// Insert code for OPENDB 

dbid = DmFindDatabase(0,"SOMEDB"); 

if (dbid ==0) 

{ 

FrmCustomAlert(Info,"Database does not exists, we must create it!",NULL,NULL); 
DmCreateDatabase(0,"SOMEDB",'DCBA','data',false); 

} 

dbid = DmFindDatabase(0,"SOMEDB"); 
if (dbid == 0) 

{ 

FrmCustomAlert(Info,"Cannot open db??",NULL,NULL); 
return true; 

} 

dbref = DmOpenDatabase(0,dbid,dmModeReadWrite); 
return true; 

} 


This code uses the DmFindDatabase function to search database card zero for a 
database named SOMEDB. If this database cannot be found, the sample application 
creates it using the DmCreateDatabase function. Once the database is created, the 
application again attempts to find it. Upon successfully finding the database and 
obtaining its LocallD, the database can be opened with a call to DmOpenDatabase. 
The final argument to the DmOpenDatabase function indicates the requested access 
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mode. The sample application requests Read/Write access, however, the Palm OS 
SDK enumerates many different access modes. 


Creating and opening a Palm OS database, 
continued 

The DmCreateDatabase function takes the following arguments: 

* Card Number -- Virtually always zero 

* Name -- A textual description of the database 

* Creator -- This is a 32-bit value indicating the owner of this database. 

* Type - This database is of type 'data'. Other database types are 'appl' for 
applications, 'rsrc' for resource, 'libr' for library, and so on. 

* Resource Database Flag - This is not a resource database, so the value is false. 

Whenever manipulating a database it is a good practice to verify its DmOpenRef . The 
sample application keeps the dbref variable set to zero when a database is not open. 
A value other than zero indicates an open database. 


Store data 

Databases store information in records. The first step in storing data is creating a new 
record. The code snippet below demonstrates creating a new record and writing a 
string value to it: 


static Boolean frmMain_ADDREC_OnSelect(EventPtr event) 

{ 

MemHandle memH; 

Char * p; 

UIntl6 recindex = dmMaxRecordlndex; 

Char buf[100]; 

// Insert code for ADDREC 
if (!dbref) return true; 

memH = DmNewRecord(dbref, Srecindex, 100) ; 
if (memH == 0) 

{ 

FrmCustomAlert(Info,"Failed to add new record :(",NULL,NULL); 
return true; 

} 

p = MemHandleLock(memH); 
if (p == NULL) 

{ 

FrmCustomAlert(Info,"Failed to lock down pointer",NULL,NULL); 
return true; 

} 

StrPrintF(buf,"Added record %d to Database",recindex); 
FrmCustomAlert(Info,buf,NULL,NULL); 

DmStrCopy(p,0,buf); 

DmReleaseRecord(dbref,recindex,true); 
return true; 


Serial and database programming for Palm OS 


Page 17 of 22 





Presented by developerWorks, your source for great tutorials 


ibm.com/developerWorks 


This code allocates a new record of 100 bytes in size. Once successfully allocated, the 
record must be locked down via the MemHandleLock function. A locked-down record 
may be modified using one of the Dm* functions. This sample uses the DmStrCopy 
function for writing null-terminated strings into records. Note the second parameter to 
the DmStrCopy function is an offset into the record. After the record is modified it must 
be released with a Call to DmReleaseRecord. 

The other options for modifying database records are DmWrite, for non-string oriented 
operations, and DmSet, for setting sections of a record to a single value. Only 
DmStrCopy, DmWrite, and DmSet are allowed to modify database records, as 
database memory is considered write-protected by the Palm OS. 

Records are manipulated by their index. Newly created records indicate their position in 
a database. This position can change when other records are added or deleted. 


Retrieve data 

Records can be searched by a classification known as a category, or they can be 
retrieved by their position in the database, or a combination of the two. Records can 
also be sorted according to application-defined rules. The sample application 
demonstrates retrieving records by position: 


static Boolean frmMain_READREC_OnSelect(EventPtr event) 

{ 

MemHandle memH; 

Char * p; 

UIntl6 recindex = dmMaxRecordlndex; 

Char buf[100]; 

UIntl6 totalrecords; 

UIntl6 i; 

// Insert code for READREC 
if (!dbref) return true; 
totalrecords = DmNumRecords(dbref); 

StrPrintF(buf,"There are %d records in this database",totalrecords) ; 
FrmCustomAlert(Info,buf,NULL,NULL); 
for (i=totalrecords-l;i != 0xffff;i—) 

{ 

memH = DmQueryRecord(dbref,i); 
if (memH) 

{ 

p = MemHandleLock(memH); 
if (P) 

{ 

FrmCustomAlert(Info,p,NULL,NULL); 

MemHandleUnlock(memH); 

} 

} 

} 

return true; 


This Retrieve Data sample above uses the DmQueryRecord function. This function 
returns a read-only handle to the record. A read-write handle can be obtained by calling 
the DmGe t Re cord function. Of course, in order to modify the record, the database 
must be opened with Write access. A record acquired by means of a DmGetRecord 
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call must be released when no longer needed. This is accomplished with the 
DmReleaseRecord function. DmQueryRecord retrievals do not require the release 
action. 


Pack those records 

Palm OS database records are stored as arrays of contiguous bytes. A record does not 
have columns or fields as is common on other platforms. This organization makes data 
retrieval and storage a little more complex than a simple Structured Query Language 
(SQL) statement. To manipulate individual fields of a record, use a technique known as 
record packing. Essentially, a complex variable type, or a C struct represents a 
record. For example, a data-collection application's database entry might look like the 
following: 

typedef struct { 

UIntl6 counter; 

UInt32 valuel; 

UInt32 value2; 

Char description[35]; 

} somerecordtype, * somerecordtypePtr; 


Writing a packed record 

The sample application, DBTester, can also write packed records. Here is the relevant 
code snippet. Notice the use here of DmWrite rather than DmStrCopy. 


static Boolean frmMain_PACKED_OnSelect(EventPtr event) 

{ 

// Insert code for PACKED 
MemHandle memH; 

Char * p; 

UIntl6 recindex = dmMaxRecordlndex; 

Char buf[100]; 
somerecordtype myrec; 
somerecordtypePtr prec; 

if (Idbref) return true; 

memH = DmNewRecord(dbref,Srecindex,sizeof(myrec)); 
if (memH == 0) 

{ 

FrmCustomAlert(Info,"Failed to add new record :(",NULL,NULL); 
return true; 

} 

prec = (somerecordtypePtr) MemHandleLock(memH); 
if (prec == NULL) 

{ 

FrmCustomAlert(Info,"Failed to lock down pointer",NULL,NULL); 
return true; 

} 

MemSet(Smyrec,0x00,sizeof(myrec)); 
myrec.counter = 1; 
myrec.valuel = 123; 
myrec.value2 = 456; 

StrPrintF(myrec.description,"Added record %d to Database",recindex) ; 
FrmCustomAlert(Info,myrec.description,NULL,NULL); 
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DmWrite(prec,0,Smyrec,sizeof(myrec)); 
DmReleaseRecord(dbref,recindex,true); 
return true; 


Reading a packed record 

In order to properly handle a packed record, an application must use the appropriate 
pointer type when locking down the record. Here is the sample application's example of 
reading and manipulating a packed database record. Note the use of the prec 
variable: 


static Boolean frmMain_READPACKED_OnSelect(EventPtr event) 

{ 

// Insert code for READPACKED 
MemHandle memH; 

Char * p; 

UIntl6 recindex = dmMaxRecordlndex; 

Char buf[100]; 

UIntl6 totalrecords; 

UIntl6 i; 

somerecordtypePtr prec; 

if (Idbref) return true; 
totalrecords = DmNumRecords(dbref); 

StrPrintF(buf,"There are %d records in this database",totalrecords); 
FrmCustomAlert(Info,buf,NULL,NULL); 
for (i=totalrecords-l;i != 0xffff;i—) 

{ 

memH = DmQueryRecord(dbref,i); 
if (memH) 

{ 

prec = (somerecordtypePtr) MemHandleLock(memH); 
if (prec) 

{ 

FrmCustomAlert(Info,prec->description,NULL,NULL); 
MemHandleUnlock(memH); 

} 

} 

} 

return true; 


Test program 

The second sample application available with this tutorial is named DBTester. It 
demonstrates all of the above techniques. To run the application, first tap on the Open 
Database button. The next steps should be done in tandem. There is a set of buttons 
for manipulating records containing strings, and a set for manipulating packed records. 
When testing is complete, be sure to tap on the Close Database button. The on page 
section contains information on obtaining the complete sample application. 
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Section 5. Conclusion 
Summary and a look ahead 

This tutorial concludes the introductory material for Palm OS data collection application 
development. The flexible facilities of Palm OS serial communications have been 
explored including both traditional wire-line and infrared links. This tutorial also 
demonstrated the use of Palm OS Data Manager functions or storing and retrieving 
information in a Palm database. 

There remains another important skill in the development of data collection 
applications: getting the data off the Palm OS organizer and into the host system. The 
next tutorial in this series, Conduit Development, will examine the process of conduit 
development with the Conduit Development Kit. The tutorial builds a sample conduit, 
demonstrating the movement of data from the device to the desktop. The DBTester 
sample application from this tutorial is leveraged to provide data for the sample conduit. 
With the ability to move data via a conduit, the complete data-collection solution for 
Palm OS is within reach. 


Resources 

* Palm OS Network Programming, by Greg Winton, is the first book dedicated to 
network programming for the Palm OS. 
(http://www.oreilly.com/catalog/palmosnetpro) 

* The lrDA.org is the standards body governing the development of infrared data 
communications protocols, (http://www.irda.org) 

* The new Serial Manager provides scaffolding for all new communications 
mechanisms available to the Palm OS. More information can be found on the new 
Serial Manager in the Palm OS SDK documentation, available from the Palm OS 
Web site, (http://www.palmos.com/dev) 

* The CommsTest and DBTester sample applications are available for download at 
http://www. palm-communications, com/ibmdw . 

* Microchip's infrared product line can be found at 
http://www.microchip.eom/11110/suppdoc/appnote/category/infrared/index.htm. 


Feedback 

Please send us your feedback on this tutorial. We look forward to hearing from you! 


Colophon 

This tutorial was written entirely in XML, using the developerWorks Toot-O-Matic tutorial 
generator. The open source Toot-O-Matic tool is an XSLT stylesheet and several XSLT 
extension functions that convert an XML file into a number of HTML pages, a zip file, JPEG 
heading graphics, and two PDF files. Our ability to generate multiple text and binary formats 
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from a single source file illustrates the power and flexibility of XML. (It also saves our 
production team a great deal of time and effort.) 

You can get the source code for the Toot-O-Matic at 

www6.software.ibm.com/dl/devworks/dw-tootomatic-p. The tutorial Building tutorials with the 
Toot-O-Matic demonstrates how to use the Toot-O-Matic to create your own tutorials. 
developerWorks also hosts a forum devoted to the Toot-O-Matic; it's available at 
www-105.ibm.com/developerworks/xml_df.nsf/AIIViewTemplate?OpenForm&RestrictToCategory=11 . 
We'd love to know what you think about the tool. 
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